---
title: Manual Installation
icon: Cog
---

Hey there! Looking to run **Palmr.** your way, with complete control over every piece of the stack? This manual installation guide is for you. No Docker, no pre-built containers just the raw source code to tweak, customize, and deploy as you see fit.

> **Prefer a quicker setup?** If this hands-on approach feels like overkill, check out our [**Quick Start (Docker)**](/docs/v3-beta/quick-start) guide for a fast, containerized deployment. This manual path is tailored for developers who want to dive deep, modify the codebase, or integrate custom services.

Here's what you'll do at a glance:

1. **Clone** the repository to get the code.
2. **Configure** `.env` files for backend and frontend.
3. **Install** JavaScript dependencies using `pnpm`.
4. **Generate** the Prisma client and run database migrations.
5. **Seed** the database with initial Palmr. data.
6. **Build & start** the backend (Fastify API).
7. **Build & serve** the frontend (Next.js app).

We've broken down each step below feel free to jump to the section you're working on!

## Before you start

Let's make sure your environment is ready to roll. Check that you've got these tools installed and set up on your system:

- <span style={{ color: "#16a34a" }}>Node.js</span> *(Powers our JavaScript/TypeScript apps)*
- <span style={{ color: "#16a34a" }}>pnpm</span> *(Our go-to package manager)*
- <span style={{ color: "#16a34a" }}>Git</span> *(For cloning and managing the repo)*

⚠️ **Heads Up on Package Managers**: Palmr. was built and tested with `pnpm`. While you _could_ try `npm`, `yarn`, or `bun`, we strongly recommend sticking with `pnpm` to avoid compatibility headaches.

---

### System requirements

- **Operating System**: MacOS or Linux (recommended for best results)
  - Windows works but hasn't been thoroughly tested.
- **Memory**: At least 4GB RAM is suggested.
- **Storage**: Depends on how much file storage you'll need.
- **CPU**: 2+ cores for smooth performance.
- **S3-Compatible Storage**: **REQUIRED** - Either:
  - External S3 service (AWS S3, DigitalOcean Spaces, etc.)
  - Local Minio server running on port 9379
  - Another S3-compatible service

---

## Let's Get Palmr. Running

### Step 1: Clone the repository

First things first, grab a local copy of the Palmr. codebase. Run this command to clone the official repo:

```bash
git clone https://github.com/kyantech/Palmr.git
```

Once it's done, you'll have a new directory with the project structure. Inside, the `apps` folder holds the key pieces: `docs`, `server`, and `web`. For this guide, we're focusing on `server` (our Fastify backend) and `web` (our Next.js frontend).

---

### Step 2: Set up the backend

Let's get the backend up and running. Start by navigating to the server directory:

```bash
cd ./apps/server
```

#### Configure environment variables

Before anything else, we need to set up the environment variables Palmr. relies on. We've included a handy template file called `.env.example` to get you started. Create your own `.env` file with this command:

```bash
cp .env.example .env
```

This copies the template into a new `.env` file with all the necessary settings. **Important**: You must configure S3-compatible storage for Palmr v3+ to work. Edit the `.env` file to either:

**Option 1: External S3 Service**
```bash
ENABLE_S3=true
S3_ENDPOINT=s3.amazonaws.com
S3_ACCESS_KEY=your-access-key
S3_SECRET_KEY=your-secret-key
S3_BUCKET_NAME=palmr-files
S3_REGION=us-east-1
```

**Option 2: Local Minio (for development)**
```bash
# First, start Minio locally:
# docker run -p 9379:9000 -e MINIO_ROOT_USER=minioadmin -e MINIO_ROOT_PASSWORD=minioadmin minio/minio server /data

ENABLE_S3=true
S3_ENDPOINT=localhost:9379
S3_ACCESS_KEY=minioadmin
S3_SECRET_KEY=minioadmin
S3_BUCKET_NAME=palmr-files
S3_USE_SSL=false
S3_FORCE_PATH_STYLE=true
```

#### Install dependencies

Next, let's install the backend dependencies. With Node.js and `pnpm` ready, run:

```bash
pnpm install
```

This pulls in everything needed for the backend, including Prisma, our database ORM.

#### Generate Prisma client

Now, generate the Prisma client tailored for Palmr. with:

```bash
pnpm dlx prisma generate
```

This sets up the interface for smooth database interactions.

#### Deploy Prisma migrations

With the client ready, apply the database schema using:

```bash
pnpm dlx prisma migrate deploy
```

This ensures your database structure is set up with all the required migrations.

#### Seed the database

Let's populate the database with some initial data. Run the seeding script:

```bash
pnpm db:seed
```

This adds the baseline data Palmr. needs to function properly.

#### Build and run the backend

Finally, build the backend app:

```bash
pnpm run build
```

Once the build is complete, start the service:

```bash
pnpm start
```

To confirm everything's working, check out the API documentation at:

```bash
http://localhost:3333/docs
```

This page lists all available API endpoints and how to use them.

---

### Step 3: Set up the frontend

With the backend humming, let's tackle the frontend setup.

#### Navigate to the Frontend Directory

If you're in the `server` folder, move to `web` with:

```bash
cd ../web
```

Or, from the repo root, use:

```bash
cd apps/web
```

#### Configure environment variables

Just like the backend, set up the frontend environment variables:

```bash
cp .env.example .env
```

This creates a `.env` file with the necessary configurations for the frontend.



#### Install dependencies

Install all the frontend dependencies:

```bash
pnpm install
```

#### Build and run the frontend

Build the production version of the frontend:

```bash
pnpm run build
```

Once that's done, serve it up:

```bash
pnpm serve
```

Now, open your browser and head to:

```bash
http://localhost:3000
```

You should see the full Palmr. application ready to go!

---

## Quick notes

**Storage Requirement**: Palmr v3+ requires S3-compatible storage to function. This guide assumes you've configured either external S3 or local Minio as shown in the environment variables section above. Without proper S3 configuration, file uploads will not work.

**Development Tip**: For local development, we recommend using Minio as it's lightweight and S3-compatible. Start it with Docker before running Palmr:

```bash
docker run -p 9379:9000 -e MINIO_ROOT_USER=minioadmin -e MINIO_ROOT_PASSWORD=minioadmin minio/minio server /data
```

### Custom Installation Paths and Symlinks

If you're using a custom installation setup with symlinks (for example, `/opt/palmr_data/uploads -> /mnt/data/uploads`), you might encounter issues with disk space detection. Palmr. includes a `CUSTOM_PATH` environment variable to handle these scenarios:

```bash
# In your .env file (apps/server/.env)
CUSTOM_PATH=/opt/palmr_data
```

This tells Palmr. to check your custom path first when determining available disk space, ensuring proper detection even when using symlinks or non-standard directory structures.

---

## Command cheat sheet

Here's a quick reference for all the commands we've covered perfect for copy-pasting once you're familiar with the steps:

```bash
# --- Prerequisites (if using local Minio) ---
docker run -p 9379:9000 -e MINIO_ROOT_USER=minioadmin -e MINIO_ROOT_PASSWORD=minioadmin minio/minio server /data

# --- Backend (Fastify API) ---
cd apps/server
pnpm install
pnpm dlx prisma generate
pnpm dlx prisma migrate deploy
pnpm db:seed
pnpm run build
pnpm start

# --- Frontend (Next.js) ---
cd apps/web
pnpm install
pnpm run build
pnpm serve
```

> **Tip**: Keep this handy in your clipboard for your first setup run.

---

## What's next?

Palmr. is now up and running locally . Here are some suggested next steps:

- **Manage Users**: Dive into the [Users Management](/docs/v3-beta/manage-users) guide.
- **Switch to Object Storage**: Update `.env` variables to use an S3-compatible bucket (see Quick Notes above).
- **Secure Your Instance**: Put Palmr. behind a reverse proxy like **Nginx** or **Caddy** and enable HTTPS.
- **Learn the Internals**: Explore how everything connects in the [Architecture](/docs/v3-beta/architecture) overview.

Jump into whichever area fits your needs our docs are designed for exploration in any order.

## Wrapping up

Congrats! You've successfully set up a production-ready instance of Palmr. through this detailed manual process. From cloning the repo to deploying the app, you've tackled every step like a pro.

## Helpful resources

- [Node.js Documentation](https://nodejs.org/en/docs/)
- [pnpm Documentation](https://pnpm.io/)
- [Prisma Documentation](https://www.prisma.io/docs/)
